Repository navigation
Add samples for experimental controls - #2233
Merged
Niels Laute (niels9001) merged 3 commits intoSep 15, 2026
Merged
Niels Laute (niels9001) merged 3 commits into
Niels Laute (niels9001) merged 3 commits into
Conversation
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Collaborator
|
/azp run |
Niels Laute (niels9001)
enabled auto-merge (squash)
September 15, 2026 09:15
Niels Laute (niels9001)
approved these changes
Sep 15, 2026
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Jaylyn Barbee (Jaylyn-Barbee)
added a commit
to Jaylyn-Barbee/WinUI-Gallery
that referenced
this pull request
Sep 15, 2026
LayoutPanel arrived in microsoft#2233 listing "Panel" and "StackLayout" under RelatedControls, which holds UniqueIds of other gallery sample pages. Neither is one: they are WinUI type names, and git history shows no commit ever added either as a sample. The exporter validates cross-references so a rename never silently produces a dead link, so Generate threw and catalog/windows-samples.json could not be regenerated by anyone on this branch - 10 tests failed on it. Nothing is lost by removing them. "Panel" is already published twice over: it is in LayoutPanel's BaseClasses, which feeds keywords, and in its Tags, which feed curatedKeywords. "StackLayout" is an ItemsRepeater layout rather than a base class of LayoutPanel, so moving it to BaseClasses would have published something false into a searchable field. ItemsRepeater, the one entry that names a real sample, stays. This also picks up the regeneration the merge in cf665c3 left outstanding: 123 controls and 333 samples, including the new experimental controls. None of the samples added by microsoft#2233 or microsoft#2234 bind an undeclared namespace prefix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Niels Laute (niels9001)
added a commit
that referenced
this pull request
Sep 16, 2026
Makes the gallery's samples readable by other tools, by publishing an
index of every page and the samples on it as a single generated JSON
file.
### Why
The gallery is where WinUI's sample code actually lives, and it's the
answer to "show me how to use this control." But that answer is only
reachable by a human browsing the app, or by a program scraping this
repo's markup. Scrapers are the norm today — `winapp find-ui` ships one
— and they break every time a page moves, a sample is renamed, or an
example changes shape. The gallery has no way to know it broke them, and
they have no way to know they're now showing stale or partial code.
Nothing here is a new sample. The samples are already written, already
reviewed, and already correct; they're just not addressable. This makes
the set the gallery already maintains available as data, so the gallery
stays the single source of truth for WinUI sample code instead of being
the thing everyone re-derives.
### What this adds
`catalog/windows-samples.json`, generated from the same `.xaml` pages
and snippet bundles that the app itself renders. 123 pages, 333 samples
— 290 with XAML, 127 with C#.
Each entry carries what a consumer needs to present a sample without
knowing anything about this repo's layout: the control's name and
description, its docs links, its keywords, and the samples themselves
with their headers and code.
```json
{
"id": "geometry",
"name": "Geometry",
"description": "Clear geometric design ensures visual coherence and structure.",
"curatedKeywords": ["path", "vector", "figures"],
"docs": [
{ "title": "Geometry in Windows 11", "uri": "https://learn.microsoft.com/windows/apps/design/signature-experiences/geometry" }
],
"samples": [
{
"header": "Geometry",
"xaml": "<Grid CornerRadius=\"{StaticResource OverlayCornerRadius}\"/>\n<Grid CornerRadius=\"{StaticResource ControlCornerRadius}\"/>"
}
]
}
```
### It's a shared format, not a gallery-specific one
The file conforms to
[`winui-sample-index.schema.json`](https://github.com/microsoft/winappCli/blob/main/docs/winui-sample-index.schema.json),
an index contract that's already published and already consumed for
other sample sources. Emitting that shape rather than inventing one
means consumers need no gallery-specific adapter, and the same shape can
describe a controls index or another sample source later. `$schema`
points at the published contract so there's one source of truth and no
copy to drift.
Fields that only make sense for this repo — the page path, the snippet
file, the gallery group — are grouped under a `gallery` object on each
control and sample, so what's contract and what's ours is obvious at a
glance.
### What makes it dependable
An index nobody can trust is worse than no index, so the generator is
built around the ways this could quietly go wrong:
**It can't drift from the samples.** The file is generated, and the PR
validation pipeline runs a step (`Verify catalog/windows-samples.json is
up to date`) that regenerates it from the current sources and fails the
build if the committed copy differs by so much as a byte. A new sample
can't land without the index following. It isn't auto-committed — the
failure tells you to run `dotnet run --project tools/CatalogExporter --
generate` and commit the result, so the index stays a reviewable part of
the diff rather than something a bot rewrites underneath you.
**Sample order is stable.** Consumers address samples positionally, so
samples are emitted in page order — the order a reader sees them in the
app. Appending is safe. Alphabetical-by-filename order was the earlier
approach and is subtly wrong: adding `ButtonA.txt` would renumber every
later sample on that page and silently repoint existing references at
different code.
**Nothing is published that a consumer will silently discard.**
Consumers drop samples whose XAML doesn't parse, which is the worst
failure mode because it looks like success on our side. The generator
runs the same well-formedness check the consumer does and reports what
it withheld.
That withholds 12 snippets, all deliberate authored elisions like
`<Window ...>` — right for the gallery's code viewer, impossible as XML.
All 12 still publish their C#, so no sample is lost.
A second check withholds 7 more: fragments that bind an XML namespace
prefix their page never declares. These parse fine in isolation, which
is why they went unnoticed, and fail only when a reader pastes them
alongside the imports we publish. That is strictly worse than malformed
XAML, because it clears our gate and breaks at their end instead of
ours. Five still publish their C#; two are XAML-only and so leave the
index entirely (`FlipviewShowingBoundData`,
`LayingOutNestedItemsrepeaters`). Both bind gallery-internal types
through `x:DataType`, so no import would have rescued them — they were
never portable, and withholding them is the honest result.
One further XAML-only snippet is dropped outright
(`OtherXamlEasingFunctions`, which uses a token as an element name
resolved from code-behind). All 20 are pinned by a test so the set can't
grow unnoticed.
**Code is published as a reader would see it.** Snippets contain
`$(Token)` placeholders bound to each page's interactive options;
published verbatim, many are not valid XAML. They now resolve to the
value the control starts with — what the gallery shows on load.
Resolution reads only what the markup states; when the answer depends on
running code, the XAML attribute carrying the token is deleted so the
property falls back to its own default, and a gate asserts none
survives. Publishing a value the gallery never shows would be worse than
publishing none. C# is the exception and is covered below.
### What maintainers are taking on
Two new top-level folders and one generated data file. Nothing existing
is restructured, and the gallery app itself gains no new runtime
dependency — the exporter is a build-time console tool that never ships
inside the app.
| Path | What it is |
| --- | --- |
| `catalog/windows-samples.json` | The generated index (10,642 lines,
684 KB). Output, not source — never hand-edit it; run `generate` and
commit the result. |
| `catalog/README.md` | Explains the format, what each field means, and
how to regenerate. Start here. |
| `tools/CatalogExporter/Program.cs` | Entry point. Two commands:
`generate` writes the index, `check` fails if the committed copy is
stale. |
| `tools/CatalogExporter/CatalogGenerator.cs` | The bulk of the logic
(670 lines): reads `ControlInfoData.json` and the sample pages, builds
the index. |
| `tools/CatalogExporter/CatalogModels.cs` | The output shape. Property
declaration order is the JSON field order. |
| `tools/CatalogExporter/SourceModels.cs` | Typed view of
`ControlInfoData.json`. |
| `tools/CatalogExporter/SampleBundle.cs` | Parses `.txt` snippet
bundles. Deliberately mirrors `ControlExample.ParseSampleCodeSections`.
|
| `tools/CatalogExporter/SubstitutionResolver.cs` | Resolves `$(Token)`
placeholders to the value each page's control starts with. |
| `tools/CatalogExporter/TokenFallback.cs` | Removes the attribute
carrying a token the resolver could not settle, and records its name.
Holds the gate that asserts no token reaches published XAML. |
| `tools/CatalogExporter/XamlFragment.cs` | The well-formedness gate and
namespace-prefix detection. |
| `tests/WinUIGallery.CatalogExporter.Tests/` | 73 tests across 6 files.
Includes the staleness guard and the pinned list of snippets whose XAML
can't be published. |
| 14 new `.txt` bundles under `Samples/AccessibilityKeyboard/` and
`Samples/AccessibilityScreenReader/` | Sample code migrated out of
inline page markup. Same code, same rendering — just reachable by
tooling now. |
Six existing files are modified, all narrowly:
| Path | Change |
| --- | --- |
| `WinUIGallery.slnx` | Adds the two new projects. |
| `.pipelines/azure-pipelines.yml` | Adds the staleness-check step
described below. |
| `ControlInfoData.json` | Adds an optional `Catalog` block to two
entries (search aliases only), and drops two dangling `RelatedControls`
references from `LayoutPanel`. |
| `ControlInfoDataSchema.json` | Documents that optional `Catalog`
block: `Exclude`, `Aliases`, `RelatedSamples`. |
| `AccessibilityKeyboardPage.xaml`, `AccessibilityScreenReaderPage.xaml`
| Inline sample code replaced with `SampleDefinition` references to the
new bundles. |
The `Catalog` block in `ControlInfoData.json` is opt-in and additive.
The running gallery app never reads it, and omitting it is the normal
case — it exists only for the rare sample that needs to override what
the exporter would otherwise derive on its own.
### What runs in CI, and when
One step is added to the existing `WinUI-Gallery-PRValidation` pipeline,
so it runs on every PR and on pushes to `main` alongside the checks
already there. No new pipeline, no new schedule, no new secrets, and
nothing that publishes anywhere.
| Step | When | What it does | How it fails |
| --- | --- | --- | --- |
| `Verify catalog/windows-samples.json is up to date` | Every PR build,
before the app build | Runs the 73 exporter tests. The key one
regenerates the index from the current sample sources and byte-compares
it to the committed file. | Build fails with the exact command to fix
it: `dotnet run --project tools/CatalogExporter -- generate`, then
commit. |
It adds roughly 7 seconds of test time plus the exporter's own build. It
never writes to the repo — no bot commits, no auto-push. A stale index
is surfaced as a failing check and fixed by the contributor, so the
generated file stays visible in review instead of changing underneath
you.
One thing worth knowing: the guard is a test, and it throws if it can't
locate the repo root rather than skipping. It can't silently pass in an
environment where it didn't really run.
### Incidental fixes found along the way
Some samples supplied their code as inline `<ControlExample.Xaml>`
markup instead of a snippet bundle. They rendered fine in the app but
were invisible to any export, with no symptom. They're migrated to
bundles, and a test fails if the inline form comes back.
`ControlInfoDataSchema.json` does not parse as strict JSON on `main`:
there's a dangling comma before a closing brace (line 101). PowerShell's
`ConvertFrom-Json` tolerates it, `JSON.parse` does not, and nothing in
CI parses this file strictly, which is how it drifted unnoticed. It
parses now — though worth flagging that the fix is positional rather
than deliberate: the new optional `Catalog` property happens to land
exactly where the dangling comma was, so the comma now separates two
real properties. Validating this file in CI would be a reasonable small
follow-up.
### Verification
Beyond the exporter's 73 tests:
- Validated against the published contract with `ajv` (draft 2020-12).
- Every published XAML fragment clears the same well-formedness check a
consumer applies, and a build-time gate fails the export outright if a
`$(Token)` reaches published XAML. Both run on every PR rather than
being spot-checked, so a consumer discards nothing: 290 XAML and 127
code blocks publish, none of the XAML carrying a placeholder.
- The gallery app builds clean, and every `SampleDefinition` reference
resolves — a dangling one compiles fine and shows an empty code viewer
at runtime. The exporter validates the full `Folder\File.txt` path
rather than just the file name, matching how `ControlExample` resolves
it at runtime.
### Notes for reviewers
- The exporter began as @niels9001's work in #2226, preserved here as
the first commit; this supersedes that PR.
- `SampleBundleParser` deliberately mirrors
`ControlExample.ParseSampleCodeSections`. If the two drift, the index
publishes code users never actually see, so the tests pin the rules most
likely to be got wrong.
- A prefix a page doesn't declare — a snippet using `local:` to mean
"your namespace" — was originally omitted from `xmlnsImports` rather
than guessed at, since an invented URI would look authoritative and not
compile. That still left the fragment published but unusable, so the
fragment itself is now withheld and the offending prefixes recorded in
`gallery.xamlOmittedUnboundPrefixes`.
- 7 pages emit zero samples because every example on them is code-less
or withheld. That's legal and visible in the output rather than hidden.
### `$(Token)` placeholders
Snippets carry `$(Token)` placeholders that the gallery substitutes at
runtime from live control values. Published verbatim they break the
contract's promise of code "exactly as it should be pasted into a
project".
**Published XAML now contains none.** The exporter resolves a token from
what the markup states; where it can't, it deletes the attribute
carrying it, so the property falls back to its own default. A build-time
gate then fails the export if any token survives in published XAML, so
the guarantee is asserted rather than assumed. 0 tokens across 290 XAML
samples, with 40 samples listing what was removed in
`gallery.xamlPlaceholdersDropped` so the omission is inspectable rather
than invisible.
The tradeoff is deliberate. A dropped attribute can leave a sample not
matching the gallery's rendering 1:1, but it always compiles. Inference
was tried and rejected: 13 sliders declare `Minimum > 0`, so a guessed
`Value` silently coerces to something the gallery never shows, and
several pages set real values in their constructors. Not resolving beats
resolving badly.
This adds no work for anyone writing a sample. A new token nobody has
taught the exporter about degrades to a dropped attribute on its own.
**C# still carries 11**, across 6 controls. The XAML approach has no C#
equivalent, because no C# construct yields a default by being absent.
The tokens appear as identifier fragments
(`BadgeNotificationGlyph.$(SelectedGlyph)`), fixed-arity arguments
(`SetBorderAndTitleBar($(HasBorder), $(HasTitleBar))`), and entire
statements, none of which can be deleted without a syntax error or
gutting the sample. Those samples publish their `code` as-is.
They are now declared rather than resolved.
`gallery.codePlaceholdersPresent` lists the token names on each of those
11 samples, so a consumer knows up front that the C# is not pasteable
instead of finding out at compile time.
It is deliberately **not** symmetric with `xamlPlaceholdersDropped`.
That field means "removed, output is clean"; this one means "still
present, output is not." A consumer conflating the two would paste
non-compiling C#, which is the exact failure the field exists to
prevent, so the names differ and `catalog/README.md` states the
asymmetry explicitly. No fatal gate is added for C#, because unlike XAML
these tokens are expected and allowed.
### What contributors need to know once this lands
Two things will surprise someone otherwise, and both are cheap to say up
front.
**Adding a sample gains a second step.** Deriving the index is
automatic: a new `Samples/{UniqueId}/` folder is picked up with no
registration, no list to append to, and no mapping table. Regenerating
it is not. Any PR that adds, renames, or removes a sample, or edits a
snippet `.txt`, has to run `dotnet run --project tools/CatalogExporter
-- generate` and commit the result, or the staleness check fails. The
failure lands on a PR whose diff may look entirely unrelated to
`catalog/`, which is the part that reads as a mystery if you haven't hit
it before. The error message names the exact command to fix it.
This branch is its own worked example. #2233 and #2234 merged while it
was open, and their three new controls and eight new samples flowed into
the index the moment the generator was next run — including #2234's
consolidation of two Windowing snippets into one, which the index
tracked as a rename with no manual intervention and no mapping to
maintain.
**`RelatedControls` gains its first consumer, and its schema description
is misleading.** `ControlInfoDataSchema.json` documents the field as
"UniqueIds of other controls" — accurate, and obeyed by 330 of the 332
references currently on `main`. It then says those values are "used to
surface 'Related controls' suggestions on the control's detail page,"
and no such code exists: the field has no `.cs` or `.xaml` reader
anywhere in `WinUIGallery/`. Until now a wrong value did nothing
observable, so nothing caught one — and an author reading that sentence
would reasonably expect a mistake to show up by running the app.
The exporter is the first thing to read the field, and it validates the
cross-references so a dangling entry is a build failure rather than a
silent dead link. `LayoutPanel` arrived from #2233 listing `Panel` and
`StackLayout`, which are WinUI type names rather than gallery pages;
both are dropped here, leaving `ItemsRepeater`. Nothing is lost, since
`Panel` was already published through `BaseClasses` and `Tags`.
Correcting that stale second sentence in the schema is a reasonable
follow-up, as it is the part that would mislead the next author.
### Follow-up, deliberately not in this PR
`WinUIGallery/Samples/SampleCode/` is a leftover from an older layout.
Of its 164 `.txt` files, **157 (~181 KB) are reachable by nothing** — no
`SampleDefinition`, no `CodeSourceFile`, no code-behind path — yet
`WinUIGallery.csproj` globs `Samples\**\*.txt`, so all of them ship
inside the app as dead payload.
The folder can't be deleted wholesale: 7 files are still loaded by name
from code-behind, 3 under `ScrollView\` (`ScrollViewPage.xaml.cs`) and 4
under `Templates\` (`TemplatesPage.xaml.cs`). Those paths are built as
runtime strings, so no build-time check catches them — worth knowing for
whoever picks up the cleanup.
---------
Co-authored-by: Niels Laute <niels.laute@live.nl>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9bdab9d1-bc7e-4bf2-8a04-610ad6c5a9b3
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This content was largely generated by AI. AI makes mistakes.
Description
FlowLayout,LayoutPanel,PagerControl, andWrapPanel.NonVirtualizingLayoutwithLayoutPanel.Motivation and Context
The Gallery should make upcoming WinUI controls discoverable while clearly distinguishing experimental APIs from stable guidance. Page-level badges avoid repeating Experimental labels on every sample within an entirely experimental page.
The FlowLayout sample deliberately uses fixed-size items because rapid scrolling with variable-sized items can trigger a layout-cycle crash, tracked by microsoft/microsoft-ui-xaml#11888.
How Has This Been Tested?
dotnet build WinUIGallery\WinUIGallery.csproj --no-restore -c Debug -p:Platform=x64 -m:1 --nologo -v:minimalThe build reports only existing nullable-reference warnings in
ItemsRepeaterCollectionPageand the expected unsigned-package warning.Types of changes